package ke07.pm.template;

/**
 * A HundredItemBag is a statically sized collection of 0 to 100 <code>T</code>
 * -typed elements. It may contain multiple equal objects, as defined by equals
 * method. However, every object reference must be unique, and may not be the
 * null reference.
 */
public interface HundredItemBag<T> {

	/**
	 * @return The total amount of stored items in this bag.
	 */
	public int size();

	/**
	 * Puts an object to the Bag.
	 * 
	 * @param obj
	 *            the object to store in the Bag.
	 * @return true if, and only if, an object equal to the given object was
	 *         already contained in the Bag before the given object was added.
	 * @throws NullPointerException
	 *             if the given object is the null reference.
	 */
	public boolean add(T obj);

	/**
	 * Removes the first occurrence of an object from the Bag.
	 * 
	 * @param obj
	 *            the object to remove.
	 * @return true if, and only if, {@link #count(T)} would return 0 after
	 *         calling this method, i.e. the given object was the last one of
	 *         its kind in the bag or there was nothing to remove.
	 * @throws IllegalArgumentException
	 *             if the given object is the null reference.
	 */
	public boolean remove(T obj);

	/**
	 * @param obj
	 *            the object to count.
	 * @return Amount of occurrences of this object in the Bag, as defined by
	 *         equals method.
	 */
	public int count(T obj);

	/**
	 * @param obj
	 *            the object to check for.
	 * @return Whether the given object is contained in the Bag.
	 */
	public boolean contains(T obj);

	/**
	 * @return A copy of all elements in this Bag as an array of T with
	 *         {@link #size()} entries.
	 */
	public T[] toArray();
}
